Requirements of the Search API

Introduction#

Recently, applications over the Internet have become data intensive. Therefore, care should be taken when querying large-scale data because it can lead to poor application performance as the data and user base grow. Consequently, more and more applications are drawn toward the search feature to allow users to find specific content in their applications in an optimized way. The search feature often comes with tools like filtering and sorting to narrow down the data to be retrieved. A general search feature present on various websites is shown below, where queries can be added in the search bar, and the gear icon represents the tools or options available for refinement.

The search feature returns high-quality results based on user queries and quickly identifies relevant information from immense amounts of data. There are multiple advantages of having the search feature, some of which are listed below:

• It’s possible to develop an autocomplete or typeahead service for users’ convenience based on what users search frequently.

• An improved content recommendation can be accomplished based on what users search most.

• Advertisements can be generated and recommended based on frequent search keywords to boost business revenue.

We identify the following functional and non-functional requirements for our search API.

Requirements#

In reality, the search API has numerous features; however, we’ll focus on some of the essential functional and non-functional requirements listed below.

Functional requirements#

• Searching: The API should return data relevant to the user query.

• Sorting: The API should sort data as per the client's preference.

• Pagination: The API should allow pagination functionality if the number of returned entries is large.

Note: To see API versioning in action, we have divided our functional requirements into two phases. This is so we can see how feature updates are implemented in real life. In the first phase, we’ll design our API that performs the basic searching, sorting, and pagination functionalities. Then, in the next phase, we'll add filtering in our API design to make it easier for users to perform a search.

Non-functional requirements#

• Availability: The API should be highly available to the users.

• Scalability: The API should have the ability to scale with the increasing amount of data and the number of search queries.

• Security: APIs should allow users to obtain results tailored to individual user behavior in a secure manner.

• Low latency: Our API should focus on generating responses with low latency irrespective of the size of the query and data set to search.

Prerequisites#

Before diving into the design phase, you must be familiar with the following concepts:

• Web API architectural styles: This chapter will help us decide which architectural style we should use for communication between the client, API gateway, and the downstream services of our search API.

• Data formats: This chapter will help us decide the data format suitable for exchanging data between the client and the search services.

• HTTP: This lesson will enable us to determine the version of HTTP suitable for the search API.

• Versioning: We’ll extend the functionality of our search service through the help of versioning.

• Back-of-the-envelope calculations: This chapter helps us to estimate the response time of the search API.

How will we design a search API?#

We've divided the API design problem into five lessons:

• Introduction to the Search Service: This lesson introduces the search service and other relevant features, such as sorting and pagination.

• Search API Design Decisions: This lesson describes the complete flow of a search API (end-to-end communication) and the architectural styles, data formats, and HTTP version that is most suitable for designing the API.

• API Model for the Search Service: This lesson will focus on the data entities and endpoints that are essential for performing different functionalities offered by the search API.

• Refinements in the Search API: This lesson covers how we can add new features to our existing design.

• Search API Design Evaluation and Latency Budget: This lesson discusses how we can achieve our non-functional requirements and estimate the response time of our API.